[TypeScript] HubSpot APIを使用してリストにコンタクトを追加する
どうも!オペ部の西村祐二です!
HubSpotのAPIを使ってコンタクトをリストに追加する処理を実装する機会がありました。備忘録を兼ねてブログにしておきます。
リストとは
特定の条件に基づいてコンタクト(顧客、リードなど)をグループ化するための機能です。リストを使うことで、マーケティングやセールスの活動を効率化し、ターゲットとなるオーディエンスに対してパーソナライズされたコミュニケーションを行うことができます。例えば、キャンペーンに関するメール通知を許可したコンタクトをリストに追加しておけば、効率よくメールマーケティングキャンペーンを行うことができます。
やってみる
今回、HubSpot APIを利用するためにNode.jsのライブラリを使用します。
環境
- Node.js: v20.11.1
- hubspot-api-nodejs: 11.2.0
- 対象のリスト:静的リスト
アクセストークンの発行
非公開アプリを作成しアクセストークンと取得します。
権限としてlistに関するスコープを付与しておきます。
- crm.lists.write
- crm.lists.read
認証タブからアクセストークンを取得できます。
リストのILSリストIDを取得する
追加したいリストのILSリストIDを取得しておきます。
ILSリストIDはリストの「詳細」から確認することができます。
ちなみにリストIDとILSリストIDの違いは以下とのことです。
リストIDは、サードパーティーの連携でリストを参照するとき、またはv1 Lists APIを使用するときに使用されます。ILS リスト ID は、Exports APIまたはv3 Lists APIを使用する際に参照されます。どちらのIDも、リストに移動して詳細をクリックすることで見つけることができる。
サンプル実装
各種ライブラリをインストール
npm install @hubspot/api-client
Typescriptをインストール
npm install typescript --save-dev
初期化
npx tsc --init --rootDir src --outDir lib --esModuleInterop --resolveJsonModule --lib es6,dom --module commonjs
アクセストークンや環境などが正常か動作確認のために、コンタクトを検索する処理で確認します。
import { Client } from "@hubspot/api-client";
import {
FilterOperatorEnum,
PublicObjectSearchRequest,
} from "@hubspot/api-client/lib/codegen/crm/companies";
const hubspotClient = new Client({
accessToken: "your token",
});
(async () => {
const objectSearchRequest: PublicObjectSearchRequest = {
filterGroups: [
{
filters: [
{
propertyName: "createdate",
operator: FilterOperatorEnum.Gte,
value: "1715709177000",
},
],
},
],
sorts: ["-createdate"],
properties: ["email", "createdate"],
limit: 100,
after: "0",
};
const response = await hubspotClient.crm.contacts.searchApi.doSearch(
objectSearchRequest
);
console.log(JSON.stringify(response, null, 2));
})();
実行
npx tsx ./test.ts
出力
うまくいけば下記のように検索結果が表示されます。
{
"total": 16,
"results": [
{
"createdAt": "2024-09-01T13:45:45.993Z",
"archived": false,
"id": "53915110775",
"properties": {
"createdate": "2024-09-01T13:45:45.993Z",
"email": "xxxxx@xxxxxxx",
"hs_object_id": "1234567890",
"lastmodifieddate": "2024-09-01T15:31:32.686Z"
},
"updatedAt": "2024-09-01T15:31:32.686Z"
},
...
]
}
環境構築ができたら次は本題のコンタクをリストを追加する処理
import { Client } from "@hubspot/api-client";
const hubspotClient = new Client({
accessToken: "your token",
});
(async () => {
const listId = 000;
const contactIds = [1234567890];
const response = await hubspotClient.crm.lists.membershipsApi.add(
listId,
contactIds
);
console.log(JSON.stringify(response, null, 2));
})();
実行
npx tsx ./test.ts
出力
{}
エラーなく実行完了したら、リストにコンタクトが追加されたか画面から確認しておきましょう
さいごに
HubSpot APIを使用してリストにコンタクトを追加する方法を紹介しました。
調べても、公式サイトぐらいしかヒットしなかったのでブログにしてみました。
誰かの参考になれば幸いです。
参考